📜 本文许可Apache 2.0

© 2026 门主引擎 · 创始人：Mooooo·📺 Bilibili🎵 Douyin💬 公众号· 联系：📧 邮箱

🚀 觉醒计划 · 配套硬件

一、学习什么是gpio_config结构体配置？

https://documentation.espressif.com/projects/esp-idf/zh_CN/latest/esp32s3/api-reference/peripherals/gpio.html

1.1 gpio_config_t结构体与IO管脚配置有什么联系？

IO 可以有两种使用方式：

• 作为简单的 GPIO 输入读取引脚上的电平，或作为简单的 GPIO 输出以输出所需的电平。
• 作为外设信号的输入/输出。

IDF 外设驱动内部会处理需要应用到引脚上的必要 IO 配置，以便它们可以用作外设信号的输入或输出。这意味着用户通常自己只需负责将 IO 配置为简单的输入或输出。gpio_config() 是一个一体化的 API，可用于配置 I/O 模式、内部上拉/下拉电阻等管脚设置，包括那些被 USB PHY 复用的引脚。

在一些应用中，IO 管脚可以同时发挥双重作用。例如，输出 LEDC PWM 信号的 IO 也可以作为 GPIO 输入生成中断或 GPIO ETM 事件。这种双重用途的 IO 管脚在配置时需要特别注意。由于 gpio_config() 是一个会覆盖所有当前配置的 API ，因此必须先调用它将管脚模式设置为 gpio_mode_t::GPIO_MODE_INPUT，然后才能调用 LEDC 驱动 API 将输出信号连接到引脚上。作为替代方案，如果除了使管脚输入启用之外不需要其他额外配置，可以随时调用 gpio_input_enable() 以实现相同的目的。

1.2 如何认识gpio_config

esp_err_t gpio_config(const gpio_config_t *pGPIOConfig) GPIO common configuration.

Configure GPIO's Mode,pull-up,PullDown,IntrType 备注

This function always overwrite all the current IO configurations

参数: pGPIOConfig -- Pointer to GPIO configure struct

返回: ESP_OK success

ESP_ERR_INVALID_ARG Parameter error

---

struct gpio_config_t

Configuration parameters of GPIO pad for gpio_config function.

Public Members

uint64_t pin_bit_mask

GPIO pin: set with bit mask, each bit maps to a GPIO

gpio_mode_t mode

GPIO mode: set input/output mode

gpio_pullup_t pull_up_en

GPIO pull-up

gpio_pulldown_t pull_down_en

GPIO pull-down

gpio_int_type_t intr_type

GPIO interrupt type

/**
 * @brief Configuration parameters of GPIO pad for gpio_config function
 */
typedef struct {
    uint64_t pin_bit_mask;          /*!< GPIO pin: set with bit mask, each bit maps to a GPIO */
    gpio_mode_t mode;               /*!< GPIO mode: set input/output mode                     */
    gpio_pullup_t pull_up_en;       /*!< GPIO pull-up                                         */
    gpio_pulldown_t pull_down_en;   /*!< GPIO pull-down                                       */
    gpio_int_type_t intr_type;      /*!< GPIO interrupt type                                  */
#if SOC_GPIO_SUPPORT_PIN_HYS_FILTER
    gpio_hys_ctrl_mode_t hys_ctrl_mode;       /*!< GPIO hysteresis: hysteresis filter on slope input    */
#endif
} gpio_config_t;

1.3 如何使用gpio_config_t结构体？

方法 A：逐个赋值（推荐初学者）

gpio_config_t io_conf = {0};  // 先清零（重要！）

io_conf.pin_bit_mask = (1ULL << GPIO_NUM_2);  // 配置 GPIO2（注意用 1ULL 防止溢出）
io_conf.mode = GPIO_MODE_INPUT;               // 设为输入模式
io_conf.pull_up_en = GPIO_PULLUP_ENABLE;      // 启用上拉电阻
io_conf.pull_down_en = GPIO_PULLDOWN_DISABLE; // 禁用下拉
io_conf.intr_type = GPIO_INTR_DISABLE;        // 不使用中断

方法 B：初始化列表（更简洁）

gpio_config_t io_conf = {
    .pin_bit_mask = (1ULL << GPIO_NUM_2),
    .mode = GPIO_MODE_INPUT,
    .pull_up_en = GPIO_PULLUP_ENABLE,
    .pull_down_en = GPIO_PULLDOWN_DISABLE,
    .intr_type = GPIO_INTR_DISABLE,
};

1.4 如何代码编写gpio_config_t结构体？

#include <stdio.h>
#include "driver/gpio.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/spi_master.h"

void app_main(void)
{

    gpio_config_t my_led_pin_config = {0};
    my_led_pin_config.pin_bit_mask = (1ULL << GPIO_NUM_2) | (1ULL << GPIO_NUM_4);
    my_led_pin_config.mode = GPIO_MODE_OUTPUT;
    my_led_pin_config.pull_up_en = GPIO_PULLUP_DISABLE;
    my_led_pin_config.pull_down_en = GPIO_PULLDOWN_DISABLE;
    my_led_pin_config.intr_type = GPIO_INTR_DISABLE;

    gpio_config(&my_led_pin_config);

    gpio_set_level(GPIO_NUM_2, 1);
    gpio_set_level(GPIO_NUM_4, 1);

    spi_bus_config_t my_spi_bus = {0};

}